<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=2">
<meta name="theme-color" content="#222">
<meta name="generator" content="Hexo 4.2.1">
  <link rel="apple-touch-icon" sizes="180x180" href="/images/apple-touch-icon-next.png">
  <link rel="icon" type="image/png" sizes="32x32" href="/images/%E6%AD%A6%E6%B1%8932x32.png">
  <link rel="icon" type="image/png" sizes="16x16" href="/images/%E6%AD%A6%E6%B1%8916x16.png">
  <link rel="mask-icon" href="/images/logo.svg" color="#222">

<link rel="stylesheet" href="/css/main.css">


<link rel="stylesheet" href="/lib1/font-awesome/css/all.min.css">
  <link rel="stylesheet" href="/lib1/pace/pace-theme-center-simple.min.css">
  <script src="/lib1/pace/pace.min.js"></script>

<script id="hexo-configurations">
    var NexT = window.NexT || {};
    var CONFIG = {"hostname":"example.com","root":"/","scheme":"Gemini","version":"7.8.0","exturl":false,"sidebar":{"position":"left","display":"post","padding":18,"offset":12,"onmobile":false},"copycode":{"enable":true,"show_result":true,"style":null},"back2top":{"enable":true,"sidebar":false,"scrollpercent":false},"bookmark":{"enable":false,"color":"#222","save":"auto"},"fancybox":false,"mediumzoom":false,"lazyload":false,"pangu":false,"comments":{"style":"tabs","active":null,"storage":true,"lazyload":false,"nav":null},"algolia":{"hits":{"per_page":10},"labels":{"input_placeholder":"Search for Posts","hits_empty":"We didn't find any results for the search: ${query}","hits_stats":"${hits} results found in ${time} ms"}},"localsearch":{"enable":true,"trigger":"auto","top_n_per_article":1,"unescape":false,"preload":false},"motion":{"enable":true,"async":false,"transition":{"post_block":"fadeIn","post_header":"slideDownIn","post_body":"slideDownIn","coll_header":"slideLeftIn","sidebar":"slideUpIn"}},"path":"search.xml"};
  </script>

  <meta name="description" content="前言背景随着越来越多的业务选择投放到小程序，但是各个平台小程序的开发模式与 Web 应用并不相同，业务上分别编码会有大量工作。而且原生小程序开发还存在着前端生态接入能力薄弱、工程化解决方案缺失、XML 模板代码晦涩笨重等问题。基于此，Rax 多端工程支持了将 Rax 多端项目转换为能在小程序端运行的代码。 使用 Rax 开发小程序，你可以一次编码多端投放。更重要的是，你可以无需学习各个平台的小程序">
<meta property="og:type" content="article">
<meta property="og:title" content="Rax小程序应用">
<meta property="og:url" content="http://example.com/2021/11/24/%E7%9B%92%E9%A9%AC%E6%8A%80%E6%9C%AF%E6%A0%88%E5%88%9D%E5%AD%A6/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/index.html">
<meta property="og:site_name" content="Technological Blog">
<meta property="og:description" content="前言背景随着越来越多的业务选择投放到小程序，但是各个平台小程序的开发模式与 Web 应用并不相同，业务上分别编码会有大量工作。而且原生小程序开发还存在着前端生态接入能力薄弱、工程化解决方案缺失、XML 模板代码晦涩笨重等问题。基于此，Rax 多端工程支持了将 Rax 多端项目转换为能在小程序端运行的代码。 使用 Rax 开发小程序，你可以一次编码多端投放。更重要的是，你可以无需学习各个平台的小程序">
<meta property="og:locale" content="zh_CN">
<meta property="og:image" content="http://example.com/image/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/O1CN01D8tZYD26YHgjaVTaN_!!6000000007673-2-tps-1350-610.png">
<meta property="og:image" content="http://example.com/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/O1CN01PpTt8X1LFhg9lzVBf_!!6000000001270-2-tps-1830-1404.png">
<meta property="article:published_time" content="2021-11-24T04:18:39.000Z">
<meta property="article:modified_time" content="2021-11-24T07:58:19.475Z">
<meta property="article:author" content="Li Yudong">
<meta property="article:tag" content="公司技术栈">
<meta name="twitter:card" content="summary">
<meta name="twitter:image" content="http://example.com/image/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/O1CN01D8tZYD26YHgjaVTaN_!!6000000007673-2-tps-1350-610.png">

<link rel="canonical" href="http://example.com/2021/11/24/%E7%9B%92%E9%A9%AC%E6%8A%80%E6%9C%AF%E6%A0%88%E5%88%9D%E5%AD%A6/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/">


<script id="page-configurations">
  // https://hexo.io/docs/variables.html
  CONFIG.page = {
    sidebar: "",
    isHome : false,
    isPost : true,
    lang   : 'zh-CN'
  };
</script>

  <title>Rax小程序应用 | Technological Blog</title>
  






  <noscript>
  <style>
  .use-motion .brand,
  .use-motion .menu-item,
  .sidebar-inner,
  .use-motion .post-block,
  .use-motion .pagination,
  .use-motion .comments,
  .use-motion .post-header,
  .use-motion .post-body,
  .use-motion .collection-header { opacity: initial; }

  .use-motion .site-title,
  .use-motion .site-subtitle {
    opacity: initial;
    top: initial;
  }

  .use-motion .logo-line-before i { left: initial; }
  .use-motion .logo-line-after i { right: initial; }
  </style>
</noscript>

</head>

<body itemscope itemtype="http://schema.org/WebPage">
  <div class="container use-motion">
    <div class="headband"></div>

    <header class="header" itemscope itemtype="http://schema.org/WPHeader">
      <div class="header-inner"><div class="site-brand-container">
  <div class="site-nav-toggle">
    <div class="toggle" aria-label="切换导航栏">
      <span class="toggle-line toggle-line-first"></span>
      <span class="toggle-line toggle-line-middle"></span>
      <span class="toggle-line toggle-line-last"></span>
    </div>
  </div>

  <div class="site-meta">

    <a href="/" class="brand" rel="start">
      <span class="logo-line-before"><i></i></span>
      <h1 class="site-title">Technological Blog</h1>
      <span class="logo-line-after"><i></i></span>
    </a>
      <p class="site-subtitle" itemprop="description">IT小白的成长之旅</p>
  </div>

  <div class="site-nav-right">
    <div class="toggle popup-trigger">
        <i class="fa fa-search fa-fw fa-lg"></i>
    </div>
  </div>
</div>




<nav class="site-nav">
  <ul id="menu" class="main-menu menu">
        <li class="menu-item menu-item-about">

    <a href="/about/" rel="section"><i class="user fa-fw"></i>关于</a>

  </li>
        <li class="menu-item menu-item-tags">

    <a href="/tags/" rel="section"><i class="tags fa-fw"></i>标签<span class="badge">18</span></a>

  </li>
        <li class="menu-item menu-item-categories">

    <a href="/categories/" rel="section"><i class="th fa-fw"></i>分类<span class="badge">14</span></a>

  </li>
        <li class="menu-item menu-item-archives">

    <a href="/archives/" rel="section"><i class="archive fa-fw"></i>归档<span class="badge">95</span></a>

  </li>
      <li class="menu-item menu-item-search">
        <a role="button" class="popup-trigger"><i class="fa fa-search fa-fw"></i>搜索
        </a>
      </li>
  </ul>
</nav>



  <div class="search-pop-overlay">
    <div class="popup search-popup">
        <div class="search-header">
  <span class="search-icon">
    <i class="fa fa-search"></i>
  </span>
  <div class="search-input-container">
    <input autocomplete="off" autocapitalize="off"
           placeholder="搜索..." spellcheck="false"
           type="search" class="search-input">
  </div>
  <span class="popup-btn-close">
    <i class="fa fa-times-circle"></i>
  </span>
</div>
<div id="search-result">
  <div id="no-result">
    <i class="fa fa-spinner fa-pulse fa-5x fa-fw"></i>
  </div>
</div>

    </div>
  </div>

</div>
    </header>

    
  <div class="back-to-top">
    <i class="fa fa-arrow-up"></i>
    <span>0%</span>
  </div>

  <a href="https://github.com/tiarmor1" class="github-corner" title="Follow me on GitHub" aria-label="Follow me on GitHub" rel="noopener" target="_blank"><svg width="80" height="80" viewBox="0 0 250 250" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a>


    <main class="main">
      <div class="main-inner">
        <div class="content-wrap">
          

          <div class="content post posts-expand">
            

    
  
  

  <article itemscope itemtype="http://schema.org/Article" class="post-block" lang="zh-CN">
    <link itemprop="mainEntityOfPage" href="http://example.com/2021/11/24/%E7%9B%92%E9%A9%AC%E6%8A%80%E6%9C%AF%E6%A0%88%E5%88%9D%E5%AD%A6/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/">

    <span hidden itemprop="author" itemscope itemtype="http://schema.org/Person">
      <meta itemprop="image" content="/images/author.jpg">
      <meta itemprop="name" content="Li Yudong">
      <meta itemprop="description" content="">
    </span>
    
    <span hidden itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
      <meta itemprop="name" content="Technological Blog">
    </span>
      <header class="post-header">
        <h1 class="post-title" itemprop="name headline">
          Rax小程序应用
        </h1>
    
        <div class="post-meta">
            <span class="post-meta-item">
              <span class="post-meta-item-icon">
                <i class="far fa-calendar"></i>
              </span>
              <span class="post-meta-item-text">发表于</span>
              
    
              <time title="创建时间：2021-11-24 12:18:39 / 修改时间：15:58:19" itemprop="dateCreated datePublished" datetime="2021-11-24T12:18:39+08:00">2021-11-24</time>
            </span>
            <span class="post-meta-item">
              <span class="post-meta-item-icon">
                <i class="far fa-folder"></i>
              </span>
              <span class="post-meta-item-text">分类于</span>
                <span itemprop="about" itemscope itemtype="http://schema.org/Thing">
                  <a href="/categories/%E7%9B%92%E9%A9%AC%E6%8A%80%E6%9C%AF%E6%A0%88/" itemprop="url" rel="index"><span itemprop="name">盒马技术栈</span></a>
                </span>
            </span>
    
          
    
        </div>
      </header>
    
    
    
    
    <div class="post-body" itemprop="articleBody">
    
      
        <h1 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h1><h2 id="背景"><a href="#背景" class="headerlink" title="背景"></a>背景</h2><p>随着越来越多的业务选择投放到小程序，但是各个平台小程序的开发模式与 Web 应用并不相同，业务上分别编码会有大量工作。而且原生小程序开发还存在着前端生态接入能力薄弱、工程化解决方案缺失、XML 模板代码晦涩笨重等问题。基于此，Rax 多端工程支持了将 Rax 多端项目转换为能在小程序端运行的代码。</p>
<p>使用 Rax 开发小程序，你可以一次编码多端投放。更重要的是，你可以无需学习各个平台的小程序语法，使用 Rax DSL 配合 Web 应用的工程配置及各种基础库，就能快速高效开发上线小程序。</p>
<p>目前，Rax 已支持阿里（支付宝、手淘、钉钉等）及微信、百度、字节跳动、快手等端。</p>
<p>Rax 小程序<strong>以运行时方案为基础</strong>，支持局部场景使用编译时方案开发组件，充分结合了二者的优势特点，让用户在保证开发效率的大前提下能够针对局部场景进行更高渲染性能的优化。</p>
<p>运行时方案：通过底层模拟 DOM 和 BOM API，使得开发者能够获得完整的 Rax 开发体验，无语法约束，同时能使用大部分 Web 生态 编译时方案：通过 AST 转译 + 运行时垫片模拟 Rax core 的方式，将源代码（Rax）1 比 1 输出为原生小程序代码，性能相对较好</p>
<p>是否还推荐编译时方案？</p>
<p>不推荐。相比运行时方案，编译时方案存在较大的劣势：</p>
<ul>
<li>第一，JSX 较为灵活，适配工作量巨大，维护成本较高，即使这样，也无法适配所有的写法；</li>
<li>第二，基于上述原因，开发者需要遵循大量的语法约束，否则代码就不能正常编译运行，开发效率难以保证；</li>
<li>第三，编译时方案需要配合一个轻量级的运行时垫片来模拟 Rax 运行，并非是真的 Rax 在运行，这意味着 Rax 有功能更新时，编译时小程序上无法得到同步；</li>
<li>第四，编译时的工程方案是基于 Webpack 自建的，无法复用 Web 工程配置;</li>
<li>最后，由于 DOM 和 BOM API 的缺失，Web 上累积的各种前端生态，基本无法在编译时小程序中复用。</li>
</ul>
<p>基于以上原因，我们不再推荐用户使用编译时方案开发完整的小程序应用，而只建议在局部组件场景下使用。</p>
<p>运行时方案与原生小程序是否具有较大的性能差距？</p>
<p>现状来看，目前已上线的部分运行时小程序项目，项目已达到较高的复杂度，即使在中端机上也能够保持较为流畅的体验度。用户可以扫码体验一下下方展示的已上线项目实际感受一下。我们也会在后续持续进行性能的优化。同时，如果实在是有一些高性能要求的局部场景无法处理，也可以使用上面所说的在运行时项目中使用编译时组件的方案。</p>
<h2 id="组件与API"><a href="#组件与API" class="headerlink" title="组件与API"></a>组件与API</h2><p>Rax 小程序支持小程序内置原生组件、自定义组件的使用，同时 为开发者提供了 Rax 基础组件及 Fusion Mobile 组件库。具体使用方式见组件使用章节。</p>
<p>为增强 Rax 跨端开发能力，我们为开发者提供了 Uni API，开发者可以通过调用这些 API 快速开发多端应用。具体使用方式见 API 章节。</p>
<h1 id="应用配置"><a href="#应用配置" class="headerlink" title="应用配置"></a>应用配置</h1><h2 id="项目创建"><a href="#项目创建" class="headerlink" title="项目创建"></a>项目创建</h2><p>执行 <code>npm init rax rax-mp-example</code> 创建项目：</p>
<p><img src="/../../image/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/O1CN01D8tZYD26YHgjaVTaN_!!6000000007673-2-tps-1350-610.png" alt="img"></p>
<p>项目创建后，用户需要进入项目目录中安装 npm 依赖：</p>
<figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">cd rax-project-01</span><br><span class="line">npm install</span><br></pre></td></tr></table></figure>

<p>Rax 跨端小程序项目默认会将代码编译到阿里小程序和微信小程序两个端，如果想开发字节、快手、百度等端的小程序，可以在 <code>build.json</code> 中 <code>targets</code> 字段中进行配置：</p>
<figure class="highlight json"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  <span class="attr">"targets"</span>: [</span><br><span class="line">    <span class="string">"miniapp"</span>,</span><br><span class="line">    <span class="string">"wechat-miniprogram"</span>,</span><br><span class="line">    <span class="string">"bytedance-microapp"</span>,  <span class="comment">// 字节跳动小程序</span></span><br><span class="line">    <span class="string">"baidu-smartprogram"</span>,  <span class="comment">// 百度智能小程序</span></span><br><span class="line">    <span class="string">"kuaishou-miniprogram"</span> <span class="comment">// 快手小程序</span></span><br><span class="line">  ]</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>接着执行 <code>npm run start</code> 即可成功启动项目，此时工程会将 Rax 代码编译为对应小程序端的代码。编译完成后，命令行中 Rax 工程会给出提示：</p>
<p><img src="/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/O1CN01PpTt8X1LFhg9lzVBf_!!6000000001270-2-tps-1830-1404.png" alt="img"></p>
<p>小程序 IDE 调试：</p>
<p>与 Web 应用不同，小程序的预览调试需要借助对应端的开发者工具。如同上方的命令行中的提示，阿里小程序和微信小程序的编译后产物分别位于 <code>build/miniapp</code> 和 <code>build/wechat-miniprogram</code> 中（未来扩展到更多的小程序端时，编译后产物也将位于 <code>build</code> 目录下）。开发者需要自行下载对应小程序的开发者工具（<a href="https://opendocs.alipay.com/mini/ide" target="_blank" rel="noopener">支付宝小程序开发者工具</a>、<a href="https://developers.weixin.qq.com/miniprogram/dev/devtools/devtools.html" target="_blank" rel="noopener">微信小程序开发者工具</a>）然后打开对应的产物文件夹，即可预览并调试小程序。</p>
<p>小程序真机预览：</p>
<p>开发者在项目目录下执行 <code>npm run build</code> 命令即可编译打包生成对应端的小程序代码。与 <code>npm run start</code> 命令相比，<code>npm run build</code> 不会生成 source map，同时会对代码进行压缩处理，因此体积将会大为减小。编译完成后，命令行中 Rax 工程同样会给出提示。此时在小程序开发者工具中点击『预览』按钮即可上传代码，使用真机扫码预览小程序。</p>
<h2 id="应用入口"><a href="#应用入口" class="headerlink" title="应用入口"></a>应用入口</h2><p>对于小程序应用，<code>src/app.tsx</code> 即整个应用的入口，通过 <code>runApp()</code> 运行应用：</p>
<figure class="highlight js"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> &#123; runApp &#125; <span class="keyword">from</span> <span class="string">'rax-app'</span>;</span><br><span class="line">runApp(&#123;&#125;);</span><br></pre></td></tr></table></figure>

<p>配置项列表：</p>
<p><code>runApp()</code> 接受一个对象作为配置参数，完整的配置参数如下：</p>
<figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> &#123; runApp &#125; <span class="keyword">from</span> <span class="string">'rax-app'</span>;</span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> appConfig = &#123;</span><br><span class="line">  app: &#123;</span><br><span class="line">    <span class="comment">// 可选，自定义添加 Provider</span></span><br><span class="line">    addProvider: <span class="function">(<span class="params">&#123; children &#125;</span>) =&gt;</span> &#123;</span><br><span class="line">      <span class="keyword">return</span> <span class="xml"><span class="tag">&lt;<span class="name">ConfigProvider</span>&gt;</span>&#123;children&#125;<span class="tag">&lt;/<span class="name">ConfigProvider</span>&gt;</span></span>;</span><br><span class="line">    &#125;,</span><br><span class="line"></span><br><span class="line">    <span class="comment">// 可选，关闭默认的 ErrorBoundary 行为，默认值为 true</span></span><br><span class="line">    errorBoundary: <span class="literal">false</span>,</span><br><span class="line"></span><br><span class="line">    <span class="comment">// 可选，自定义错误边界的 fallback UI</span></span><br><span class="line">    ErrorBoundaryFallback: <span class="xml"><span class="tag">&lt;<span class="name">div</span>&gt;</span>渲染错误<span class="tag">&lt;/<span class="name">div</span>&gt;</span></span>,</span><br><span class="line"></span><br><span class="line">    <span class="comment">// 可选，自定义错误的处理事件</span></span><br><span class="line">    onErrorBoundaryHander: (error, componentStack) &#123;</span><br><span class="line">      <span class="comment">// Do something with the error</span></span><br><span class="line">    &#125;,</span><br><span class="line"></span><br><span class="line">    <span class="comment">// 可选，小程序应用生命周期</span></span><br><span class="line">    onLaunch() &#123;&#125;,</span><br><span class="line">    onShow() &#123;&#125;,</span><br><span class="line">    onHide() &#123;&#125;,</span><br><span class="line">    onError() &#123;&#125;,</span><br><span class="line">    onShareAppMessage() &#123;&#125;</span><br><span class="line">  &#125;,</span><br><span class="line">  store: &#123;</span><br><span class="line">    initialStates: &#123;&#125;,</span><br><span class="line">    getInitialStates: <span class="function">(<span class="params">initialData</span>) =&gt;</span> &#123;&#125;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;;</span><br><span class="line"></span><br><span class="line">runApp(appConfig);</span><br></pre></td></tr></table></figure>

<p>当在 <code>app.ts</code> 中包含 <code>JSX</code> 元素的时候，需要将 <code>app.ts</code> 更名为 <code>app.tsx</code></p>
<p> 编译后，<code>pages/Home/index.json</code> 中将包含 <code>&quot;barButtonTheme&quot;: &quot;default&quot;</code> 的配置，<code>pages/About/index.json</code> 中将包含 <code>&quot;barButtonTheme&quot;: &quot;light&quot;</code> 的配置。</p>
<p>window</p>
<p>可以设置应用的窗口表现，同时也支持针对每个页面设置窗口表现。目前已经支持的参数的有：</p>
<table>
<thead>
<tr>
<th align="left">属性</th>
<th align="left">描述</th>
</tr>
</thead>
<tbody><tr>
<td align="left">title</td>
<td align="left">页面标题</td>
</tr>
<tr>
<td align="left">pullRefresh</td>
<td align="left">是否允许下拉刷新</td>
</tr>
<tr>
<td align="left">titleBarColor</td>
<td align="left">导航栏背景色，十进制颜色值（0-255）</td>
</tr>
</tbody></table>
<figure class="highlight json"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  <span class="attr">"routes"</span>: [                    </span><br><span class="line">    &#123;</span><br><span class="line">      <span class="attr">"path"</span>: <span class="string">"/"</span>,</span><br><span class="line">      <span class="attr">"source"</span>: <span class="string">"pages/Home/index"</span></span><br><span class="line">    &#125;,</span><br><span class="line">    &#123;</span><br><span class="line">      <span class="attr">"path"</span>: <span class="string">"/about"</span>,</span><br><span class="line">      <span class="attr">"source"</span>: <span class="string">"pages/About/index"</span>,</span><br><span class="line">      <span class="attr">"window"</span>: &#123;</span><br><span class="line">        <span class="attr">"title"</span>: <span class="string">"关于 Rax"</span></span><br><span class="line">      &#125;</span><br><span class="line">    &#125;</span><br><span class="line">  ],</span><br><span class="line">  <span class="attr">"window"</span>: &#123;</span><br><span class="line">    <span class="attr">"title"</span>: <span class="string">"应用默认 title"</span></span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>其它没有列出的属性，可以直接参照各平台小程序自己的配置填写，详见下方相关链接。</p>
<p>tabBar</p>
<p>如果你的应用是一个多 tab 应用（底部栏可以切换页面），那么可以通过 <code>tabBar</code> 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页面。</p>
<figure class="highlight json"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  <span class="attr">"routes"</span>: [</span><br><span class="line">    &#123;</span><br><span class="line">      <span class="attr">"path"</span>: <span class="string">"/"</span>,</span><br><span class="line">      <span class="attr">"source"</span>: <span class="string">"pages/Home/index"</span></span><br><span class="line">    &#125;</span><br><span class="line">  ],</span><br><span class="line">  <span class="attr">"tabBar"</span>: &#123;</span><br><span class="line">    <span class="attr">"textColor"</span>: <span class="string">"#999"</span>,</span><br><span class="line">    <span class="attr">"selectedColor"</span>: <span class="string">"#666"</span>,</span><br><span class="line">    <span class="attr">"backgroundColor"</span>: <span class="string">"#f8f8f8"</span>,</span><br><span class="line">    <span class="attr">"items"</span>: [</span><br><span class="line">      &#123;</span><br><span class="line">        <span class="attr">"text"</span>: <span class="string">"home"</span>,</span><br><span class="line">        <span class="attr">"pageName"</span>: <span class="string">"/"</span>,</span><br><span class="line">        <span class="attr">"icon"</span>: <span class="string">"https://gw.alicdn.com/tfs/TB1ypSMTcfpK1RjSZFOXXa6nFXa-144-144.png"</span>,</span><br><span class="line">        <span class="attr">"activeIcon"</span>: <span class="string">"https://gw.alicdn.com/tfs/TB1NBiCTgHqK1RjSZFPXXcwapXa-144-144.png"</span></span><br><span class="line">      &#125;</span><br><span class="line">    ]</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>tabBar 配置项如下：</p>
<table>
<thead>
<tr>
<th align="left">属性</th>
<th align="left">类型</th>
<th align="left">是否必填</th>
<th align="left">描述</th>
</tr>
</thead>
<tbody><tr>
<td align="left">textColor</td>
<td align="left">HexColor</td>
<td align="left">否</td>
<td align="left">文字颜色</td>
</tr>
<tr>
<td align="left">selectedColor</td>
<td align="left">HexColor</td>
<td align="left">否</td>
<td align="left">选中文字颜色</td>
</tr>
<tr>
<td align="left">backgroundColor</td>
<td align="left">HexColor</td>
<td align="left">否</td>
<td align="left">背景色</td>
</tr>
<tr>
<td align="left">items</td>
<td align="left">Array</td>
<td align="left">是</td>
<td align="left">每个 tab 配置</td>
</tr>
</tbody></table>
<p>tab item 配置项如下：</p>
<table>
<thead>
<tr>
<th align="left">属性</th>
<th align="left">类型</th>
<th align="left">必填</th>
<th align="left">描述</th>
</tr>
</thead>
<tbody><tr>
<td align="left">pageName</td>
<td align="left">String</td>
<td align="left">是</td>
<td align="left">设置页面路径，值为 <code>routes</code> 中配置的路由</td>
</tr>
<tr>
<td align="left">text</td>
<td align="left">String</td>
<td align="left">是</td>
<td align="left">tab item 上显示的文本</td>
</tr>
<tr>
<td align="left">icon</td>
<td align="left">String</td>
<td align="left">否</td>
<td align="left">非选中状态图标路径</td>
</tr>
<tr>
<td align="left">activeIcon</td>
<td align="left">String</td>
<td align="left">否</td>
<td align="left">选中状态图标路径</td>
</tr>
</tbody></table>
<p>阿里小程序其它的 tabBar 配置可见<a href="https://opendocs.alipay.com/mini/framework/app-json" target="_blank" rel="noopener">此文档</a> 。</p>
<p>注意</p>
<ol>
<li>原生小程序中 <code>app.json</code> 的其他字段（如 <code>networkTimeout</code>、<code>debug</code> 等）均可在 <code>src/app.json</code> 中直接配置</li>
<li>关于分包加载的配置，参考分包加载章节。</li>
<li>阿里和微信小程序中的配置如果属于各端独有，那么可正常按照其文档说明配置；如某一配置双端均存在，则以阿里小程序的字段为准。如开启全局的下拉刷新配置，在微信小程序中为 <code>enablePullDownRefresh</code> 字段，在阿里小程序中则为 <code>pullRefresh</code>，用户统一配置为 <code>pullRefresh</code> 即可。(<code>title</code> 除外，其对应阿里小程序中的 <code>defaultTitle</code> 和微信小程序中的 <code>navigationBarTitleText</code>)。</li>
<li>阿里小程序中接受 ‘YES’/‘NO’ 的字段（如 <code>allowsBounceVertical</code>），在 Rax 中请使用 <code>true/false</code> 配置。</li>
</ol>
<p>相关链接</p>
<ul>
<li><a href="https://opendocs.alipay.com/mini/framework/app-json" target="_blank" rel="noopener">阿里小程序 app.json 应用配置</a></li>
<li><a href="https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html" target="_blank" rel="noopener">微信小程序全局配置</a></li>
</ul>
<h2 id="工程配置"><a href="#工程配置" class="headerlink" title="工程配置"></a>工程配置</h2><p>基础指南的工程配置章节介绍了应用整体的工程配置，本节着重介绍小程序独有的工程配置。</p>
<p>如何配置需要开发的小程序端：</p>
<p>目前 Rax 支持开发阿里、微信、字节、百度、快手小程序，需要开发者在 <code>build.json</code> 中配置 <code>targets</code> 字段。其对应字段名如下：</p>
<table>
<thead>
<tr>
<th align="left">小程序平台</th>
<th align="left">target 字段名</th>
</tr>
</thead>
<tbody><tr>
<td align="left">阿里小程序</td>
<td align="left">miniapp</td>
</tr>
<tr>
<td align="left">微信小程序</td>
<td align="left">wechat-miniprogram</td>
</tr>
<tr>
<td align="left">字节跳动小程序</td>
<td align="left">bytedance-microapp</td>
</tr>
<tr>
<td align="left">百度小程序</td>
<td align="left">baidu-smartprogram</td>
</tr>
<tr>
<td align="left">快手小程序</td>
<td align="left">kuaishou-miniprogram</td>
</tr>
</tbody></table>
<p>完整的小程序 <code>targets</code> 配置如下示例：</p>
<figure class="highlight json"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  <span class="attr">"targets"</span>: [</span><br><span class="line">    <span class="string">"miniapp"</span>, </span><br><span class="line">    <span class="string">"wechat-miniprogram"</span>, </span><br><span class="line">    <span class="string">"bytedance-microapp"</span>, </span><br><span class="line">    <span class="string">"baidu-smartprogram"</span>, </span><br><span class="line">    <span class="string">"kuaishou-miniprogram"</span></span><br><span class="line">  ]</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>注意：目前字节跳动小程序、百度智能小程序、快手小程序仍处于实验性阶段，如果遇到问题可至 <a href="https://github.com/raxjs/miniapp/issues" target="_blank" rel="noopener">Github issue</a> 留言，我们将快速跟进支持。</p>
<h4 id="添加小程序配置"><a href="#添加小程序配置" class="headerlink" title="添加小程序配置"></a>添加小程序配置</h4><p>在 <code>build.json</code> 中，配置 <code>targets</code> 如下所示：</p>
<figure class="highlight json"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  <span class="attr">"targets"</span>: [<span class="string">"miniapp"</span>, <span class="string">"wechat-miniprogram"</span>],</span><br><span class="line">  <span class="attr">"miniapp"</span>: &#123;&#125;,</span><br><span class="line">  <span class="attr">"wechat-miniprogram"</span>: &#123;&#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>此时表示开发阿里小程序和微信小程序，小程序端独有配置可分别在 <code>miniapp</code> 和 <code>wechat-miniprogram</code> 中添加。</p>
<p>下面列出小程序端的独有配置项：</p>
<p>buildType</p>
<ul>
<li>类型：<code>string</code></li>
<li>默认值：<code>runtime</code></li>
</ul>
<p>小程序引擎选择，默认为运行时引擎。如需启用编译时引擎，则配置为 <code>compile</code>。</p>
<p>nativeConfig</p>
<ul>
<li>类型：<code>object</code></li>
<li>默认值：<code>/</code></li>
</ul>
<p>小程序原生配置文件内容，即支付宝的 <code>mini.project.json</code>，微信的 <code>project.config.json</code>。</p>
<p>subPackages</p>
<ul>
<li>类型：<code>boolean|object</code></li>
<li>默认值：<code>false</code></li>
</ul>
<p>是否开启分包加载。当配置为 <code>object</code> 时，可使用布尔值属性 <code>shareMemory</code> 来决定是否需要共享运行时内存：</p>
<figure class="highlight json"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  <span class="attr">"miniapp"</span>: &#123;</span><br><span class="line">    <span class="attr">"subPackages"</span>: &#123;</span><br><span class="line">      <span class="attr">"shareMemory"</span>: <span class="literal">true</span></span><br><span class="line">    &#125;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>runtimeDependencies</p>
<ul>
<li>类型：<code>array</code></li>
<li>默认值：<code>[]</code></li>
</ul>
<p>仅运行时项目生效。用于决定当运行时项目中使用到由 Rax 组件工程产出的多端组件 npm 包时，使用其编译时实现或运行时实现。数组中的每一项为字符串或正则表达式，命中的 npm 包名将启用其运行时的组件实现。</p>
<p>nativePackage</p>
<ul>
<li>类型：<code>object</code></li>
<li>默认值：<code>{}</code></li>
</ul>
<p>用于配置安装 Rax 项目中的原生小程序自定义组件及原生页面所用到的 npm 依赖。其中，布尔值属性 <code>autoInstall</code> 用于指定是否自动安装 Rax 项目中的原生小程序自定义组件及原生页面所用到的 npm 依赖。而 <code>dependencies</code> 则用于配置 Rax 项目中的原生小程序自定义组件及原生页面所用到的 npm 依赖，其格式与 <code>package.json</code> 中的 <code>dependencies</code> 字段一致。</p>
<p>当不配置 <code>dependencies</code> 字段且 <code>autoInstall</code> 未设置为 <code>false</code>, Rax 工程默认会在产物文件夹中安装 Rax 项目用到的所有依赖，可能产生冗余从而导致小程序体积变大。因此建议使用原生代码时务必配置此属性。</p>
<figure class="highlight json"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  <span class="attr">"miniapp"</span>: &#123;</span><br><span class="line">    <span class="attr">"nativePackage"</span>: &#123;</span><br><span class="line">      <span class="attr">"autoInstall"</span>: <span class="literal">true</span>,</span><br><span class="line">      <span class="attr">"dependencies"</span>: &#123;</span><br><span class="line">        <span class="attr">"mini-ali-ui"</span>: <span class="string">"^1.3.4"</span></span><br><span class="line">      &#125;</span><br><span class="line">    &#125;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>注意</p>
<ul>
<li>当运行时项目中使用到由 Rax 组件工程产出的多端组件 npm 包时，如果不配置 <code>runtimeDependencies</code>， 则默认采用其编译时的代码实现。此时需要将其配置到 <code>nativePackage.dependencies</code>，否则产物中将报找不到该组件的问题。</li>
<li><code>nativePackage.dependencies</code> 中配置的原生小程序 npm 依赖依然需要在 Rax 项目根目录的 <code>package.json</code> 中配置并安装</li>
</ul>
<h4 id="示例配置"><a href="#示例配置" class="headerlink" title="示例配置"></a>示例配置</h4><figure class="highlight json"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  <span class="attr">"targets"</span>: [<span class="string">"miniapp"</span>, <span class="string">"wechat-miniprogram"</span>],</span><br><span class="line">  <span class="attr">"wechat-miniprogram"</span>: &#123;</span><br><span class="line">    <span class="attr">"nativeConfig"</span>: &#123;</span><br><span class="line">      <span class="attr">"appId"</span>: YOUR_APP_ID,</span><br><span class="line">      <span class="attr">"miniprogramRoot"</span>: <span class="string">"build/wechat-miniprogram"</span></span><br><span class="line">    &#125;,</span><br><span class="line">    <span class="attr">"subPackages"</span>: &#123;</span><br><span class="line">      <span class="attr">"shareMemory"</span>: <span class="literal">true</span></span><br><span class="line">    &#125;,</span><br><span class="line">    <span class="attr">"runtimeDependencies"</span>: [<span class="string">"@ali/comp1"</span>, <span class="string">"/^raxcomp/"</span>],</span><br><span class="line">    <span class="attr">"nativePackage"</span>: &#123;</span><br><span class="line">      <span class="attr">"autoInstall"</span>: <span class="literal">true</span>,</span><br><span class="line">      <span class="attr">"dependencies"</span>: &#123;</span><br><span class="line">        <span class="attr">"mini-ali-ui"</span>: <span class="string">"^1.3.4"</span></span><br><span class="line">      &#125;</span><br><span class="line">    &#125;</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<h1 id="应用开发"><a href="#应用开发" class="headerlink" title="应用开发"></a>应用开发</h1><h2 id="生命周期及事件处理"><a href="#生命周期及事件处理" class="headerlink" title="生命周期及事件处理"></a>生命周期及事件处理</h2><p>在 Rax小程序的迭代过程中，我们移除了一些系列和原生小程序事件相关的 Hook。背后的设计存在两个主要原因：（1）<code>useHistory</code> <code>useReachBottom</code> 等 Hook 的实现，其实并不是真正的 Hook，只是单纯的 API，所以这不符合 Hook 的命名以及设计；（2）性能与可扩展性较弱，每当小程序新支持一个事件，都需要去开发一个对应功能的 API，并且在页面初始化之初就监听所有事件，这是极为不合理的。</p>
<h3 id="API"><a href="#API" class="headerlink" title="API"></a>API</h3><p>基于以上，我们提供了 3 个 API 来取代之前的功能：<code>registerNativeEventListeners</code> <code>addNativeEventListener</code> <code>removeNativeEventListener</code> 。</p>
<table>
<thead>
<tr>
<th align="left">方法名</th>
<th align="left">描述</th>
</tr>
</thead>
<tbody><tr>
<td align="left"><code>registerNativeEventListeners(Component, [...eventName])</code></td>
<td align="left">注册该页面需要监听的所有事件，第一个参数为页面级组件</td>
</tr>
<tr>
<td align="left"><code>addNativeEventListener(eventName, callback)</code></td>
<td align="left">开始监听某个事件并执行回调函数</td>
</tr>
<tr>
<td align="left"><code>removeNativeEventListener(eventName, callback)</code></td>
<td align="left">移除某个事件的回调函数</td>
</tr>
</tbody></table>
<p>具体用法如下：</p>
<figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> &#123; createElement, useEffect &#125; <span class="keyword">from</span> <span class="string">'rax'</span>;</span><br><span class="line"><span class="keyword">import</span> View <span class="keyword">from</span> <span class="string">'rax-view'</span>;</span><br><span class="line"><span class="keyword">import</span> Text <span class="keyword">from</span> <span class="string">'rax-text'</span>;</span><br><span class="line"><span class="keyword">import</span> &#123; isMiniApp &#125; <span class="keyword">from</span> <span class="string">'universal-env'</span>; </span><br><span class="line"><span class="keyword">import</span> &#123; registerNativeEventListeners, addNativeEventListener, removeNativeEventListener &#125; <span class="keyword">from</span> <span class="string">'rax-app'</span>;</span><br><span class="line"></span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">function</span> <span class="title">Index</span>(<span class="params"></span>) </span>&#123;</span><br><span class="line">  <span class="function"><span class="keyword">function</span> <span class="title">handlePageReachBottom</span>(<span class="params"></span>) </span>&#123;&#125;</span><br><span class="line">  useEffect(<span class="function"><span class="params">()</span> =&gt;</span> &#123;</span><br><span class="line">    <span class="keyword">if</span>(isMiniApp) &#123;</span><br><span class="line">      <span class="comment">// 开始监听 onReachBottom 事件</span></span><br><span class="line">      addNativeEventListener(<span class="string">'onReachBottom'</span>, handlePageReachBottom);</span><br><span class="line">    &#125;</span><br><span class="line">    <span class="keyword">return</span> <span class="function"><span class="params">()</span> =&gt;</span> &#123;</span><br><span class="line">      <span class="keyword">if</span> (isMiniApp) &#123;</span><br><span class="line">      <span class="comment">// 移除onReachBottom 事件的监听器</span></span><br><span class="line">      removeNativeEventListener(<span class="string">'onReachBottom'</span>, handlePageReachBottom);</span><br><span class="line">    &#125;</span><br><span class="line">    &#125;</span><br><span class="line">  &#125;, []);</span><br><span class="line"></span><br><span class="line">  <span class="keyword">return</span> (</span><br><span class="line">    &lt;View&gt;</span><br><span class="line">      &lt;Text&gt;<span class="number">1</span>&lt;<span class="regexp">/Text&gt;</span></span><br><span class="line"><span class="regexp">    &lt;/</span>View&gt;</span><br><span class="line">  );</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">if</span> (isMiniApp) &#123;</span><br><span class="line">  registerNativeEventListeners(Index, [<span class="string">'onReachBottom'</span>]);</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">export</span> <span class="keyword">default</span> Index;</span><br></pre></td></tr></table></figure>

<p>以上方式适用于绝大多数小程序内的页面生命周期以及其他注册在原生 <code>Page</code> 上的页面事件处理函数，如 <code>onPullDownRefresh</code>/<code>onShareAppMessage</code>/ 等。同时，基础里生命周期章节提到的页面生命周期 hooks 同样可以使用。目前支持的页面生命周期及事件处理函数列表如下：</p>
<ul>
<li>页面生命周期函数<ul>
<li>onShow</li>
<li>onHide</li>
<li>onUnload</li>
</ul>
</li>
<li>页面事件处理函数：<ul>
<li><a href="https://opendocs.alipay.com/mini/framework/page-detail#%E9%A1%B5%E9%9D%A2%E4%BA%8B%E4%BB%B6%E5%A4%84%E7%90%86%E5%87%BD%E6%95%B0" target="_blank" rel="noopener">阿里小程序页面事件处理函数</a></li>
<li><a href="https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html" target="_blank" rel="noopener">微信小程序页面事件处理函数</a></li>
</ul>
</li>
</ul>
<h3 id="注意"><a href="#注意" class="headerlink" title="注意"></a>注意</h3><ul>
<li>我们更希望开发者能够尽可能的使用 Rax 已有的生命周期的概念。比如 <code>onLoad</code>，更应该使用 <code>componentDidMount</code> 的概念来做。所以目前原生事件监听目前不支持 <code>onLoad</code> <code>onReady</code>。</li>
<li>对于 <code>onShow</code> 生命周期，Function Components 中使用 <code>usePageShow(callback)</code> 时传入的 callback 函数会在组件完成渲染后再执行， Class Component 中使用的 <code>onShow()</code> 则会在组件 <code>constructor</code> 之后调用，详见生命周期章节。<strong>推荐使用以上两种方式处理。</strong>如果想使用 <code>addNativeEventListener</code> 监听 <code>onShow</code> 生命周期（<strong>不推荐</strong>），则需要注意调用 <code>addNativeEventListener</code> 的代码需要在 <code>useEffect</code> 外部，否则无法监听页面的首次 <code>onShow</code>，同时需要在 <code>useEffect</code> 返回的清除函数中卸载监听，示例如下：</li>
</ul>
<figure class="highlight js"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> &#123; createElement, useEffect &#125; <span class="keyword">from</span> <span class="string">'rax'</span>;</span><br><span class="line"><span class="keyword">import</span> View <span class="keyword">from</span> <span class="string">'rax-view'</span>;</span><br><span class="line"><span class="keyword">import</span> Text <span class="keyword">from</span> <span class="string">'rax-text'</span>;</span><br><span class="line"><span class="keyword">import</span> &#123; registerNativeEventListeners, addNativeEventListener, removeNativeEventListener &#125; <span class="keyword">from</span> <span class="string">'rax-app'</span>;</span><br><span class="line"></span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">function</span> <span class="title">Index</span>(<span class="params"></span>) </span>&#123;</span><br><span class="line">  <span class="function"><span class="keyword">function</span> <span class="title">handlePageShow</span>(<span class="params"></span>) </span>&#123;&#125;</span><br><span class="line">  addNativeEventListener(<span class="string">'onShow'</span>, handlePageShow);</span><br><span class="line">  useEffect(<span class="function"><span class="params">()</span> =&gt;</span> &#123;</span><br><span class="line">    <span class="keyword">return</span> <span class="function"><span class="params">()</span> =&gt;</span> &#123;</span><br><span class="line">      removeNativeEventListener(<span class="string">'onShow'</span>, handlePageShow);</span><br><span class="line">    &#125;</span><br><span class="line">  &#125;);</span><br><span class="line">  <span class="keyword">return</span> (</span><br><span class="line">    &lt;View&gt;</span><br><span class="line">      &lt;Text&gt;<span class="number">1</span>&lt;<span class="regexp">/Text&gt;</span></span><br><span class="line"><span class="regexp">    &lt;/</span>View&gt;</span><br><span class="line">  );</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">registerNativeEventListeners(Index, [<span class="string">'onShow'</span>]);</span><br><span class="line"></span><br><span class="line"><span class="keyword">export</span> <span class="keyword">default</span> Index;</span><br></pre></td></tr></table></figure>

<h2 id="组件使用"><a href="#组件使用" class="headerlink" title="组件使用"></a>组件使用</h2><p>为扩展 Rax 小程序的跨端能力，我们提供了 Rax 基础组件及 Fusion Mobile 组件库供用户使用，提供多端一致的体验。同时，Rax 也支持小程序原生组件的使用，为开发者在各个端定制性的需求上提供完整的能力。以下为几种类型的组件的使用方法：</p>
<p>所有小程序内置组件可在 Rax 项目中直接使用，但是需要注意按照 JSX 语法编写代码。例如，在小程序原生项目中按照以下方式使用的组件：</p>
<figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">&lt;!-- 阿里小程序 --&gt;</span><br><span class="line">&lt;button type=<span class="string">"&#123;&#123;customType&#125;&#125;"</span> onTap=<span class="string">"clickMe"</span>&gt;我是按钮&lt;<span class="regexp">/button&gt;</span></span><br><span class="line"><span class="regexp"></span></span><br><span class="line"><span class="regexp">&lt;!-- 微信小程序 --&gt;</span></span><br><span class="line"><span class="regexp">&lt;button type="&#123;&#123;customType&#125;&#125;" bindtap="clickMe" bindgetphonenumber="handleGetPhoneNumber"&gt;我是按钮&lt;/</span>button&gt;</span><br></pre></td></tr></table></figure>

<p>对应在 Rax JSX 中应该这样使用：</p>
<figure class="highlight jsx"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">&lt;button type=&#123;customType&#125; onClick=&#123;clickMe&#125; onGetPhoneNumber=&#123;handleGetPhoneNumber&#125;&gt;我是按钮&lt;<span class="regexp">/button&gt;</span></span><br></pre></td></tr></table></figure>

<p>特别注意，在微信等小程序端通过 <code>bind</code> 前缀绑定事件，在 JSX 中需要处理为 <code>on</code> 前缀，并遵循驼峰式命名规则，如上面 <code>bindgetphonenumber</code> 处理为 <code>onGetPhoneNumber</code>。</p>
<h4 id="自定义组件"><a href="#自定义组件" class="headerlink" title="自定义组件"></a>自定义组件</h4><p>Rax 小程序使用小程序原生组件目前支持以下两种方式：</p>
<ul>
<li>通过 npm 安装</li>
<li>将源码拷贝至本地使用</li>
</ul>
<p>使用原生组件时，请注意配置 <code>nativePackage</code> 的 <code>dependencies</code>，否则 Rax 工程会默认在产物文件中安装项目用到的所有依赖，可能会造成冗余，具体请参考小程序工程配置章节的<code>nativePackage</code>。</p>
<p>通过 npm 安装</p>
<p>你可以通过 npm 安装的方式在 Rax 项目中使用小程序原生组件。</p>
<p>开发者个人 npm 包</p>
<p>如果该原生组件由开发者控制，则建议在 package.json 中配置 <code>miniappConfig</code> 字段，其中 <code>main</code> 属性的值指向小程序原生组件的入口路程。例如，你的小程序原生组件目录结构如下所示：</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">├── README.md</span><br><span class="line">├── lib</span><br><span class="line">   └── miniapp</span><br><span class="line">       ├── index.acss</span><br><span class="line">       ├── index.axml</span><br><span class="line">       ├── index.js</span><br><span class="line">       ├── index.json</span><br><span class="line">├── package.json</span><br></pre></td></tr></table></figure>

<p>则 miniappConfig 字段的值为 <code>{ &quot;main&quot;: &quot;lib/miniapp/index&quot; }</code>。 配置 miniappConfig 字段后，用户可按照 <code>import Button from &#39;your-custom-component&#39;</code> 的方式引入组件使用。</p>
<p>第三方 npm 组件包</p>
<p>若开发者引用的是第三方 npm 组件包，无法在 package.json 中配置 miniappConfig，则用户可以直接按照具体路径引用组件：<code>import Title from &#39;mini-ali-ui/es/title/index&#39;</code>。</p>
<p>将源码拷贝至本地使用</p>
<p>直接将小程序原生组件代码拷贝至 <code>src/miniapp-native</code> 目录下，并按具体路径引用组件即可使用：<code>import Button from &#39;../../miniapp-native/Button/index&#39;</code>。（注：请勿使用 alias 路径）</p>
<h4 id="Rax-基础组件"><a href="#Rax-基础组件" class="headerlink" title="Rax 基础组件"></a>Rax 基础组件</h4><p>目前 Rax 基础组件绝大多数均支持小程序端，使用方式详见基础元件文档。</p>
<h4 id="Fusion-Mobile"><a href="#Fusion-Mobile" class="headerlink" title="Fusion Mobile"></a>Fusion Mobile</h4><p>Fusion Mobile 是基于 Rax 的一套无线端组件，涵盖了业务中 80% 的常见 UI 场景，支持在 Web 以及 Rax 小程序运行时中使用。详见基础组件文档。</p>
<h2 id="小程序-API"><a href="#小程序-API" class="headerlink" title="小程序 API"></a>小程序 API</h2><h3 id="Uni-API"><a href="#Uni-API" class="headerlink" title="Uni API"></a>Uni API</h3><p>为扩展 Rax 体系能力边界，我们为开发者提供了一系列的 Universal API，开发者可以通过调用这些 API 快速开发多端应用。</p>
<p>全新的 Universal API 升级版 Uni API 现已发布，提供更丰富完善的 API，支持 Web、微信小程序、阿里小程序、字节小程序等多种环境，开箱即用，快速接入，更支持按环境拆包，提供更极致的代码体积，体验升级。使用方式详见 Uni API 文档。</p>
<h3 id="原生小程序-API"><a href="#原生小程序-API" class="headerlink" title="原生小程序 API"></a>原生小程序 API</h3><p>对于 Uni API 没有覆盖到的场景，你也可以直接在 Rax 小程序中使用阿里小程序的 <code>my</code> API及微信小程序的 <code>wx</code> API。此时如果仍有跨端诉求，你可以结合 <code>@uni/env</code> 进行处理，示例如下：</p>
<figure class="highlight js"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> &#123; isMiniApp, isWeChatMiniProgram &#125; <span class="keyword">from</span> <span class="string">'@uni/env'</span>;</span><br><span class="line"></span><br><span class="line"><span class="function"><span class="keyword">function</span> <span class="title">scan</span>(<span class="params"></span>) </span>&#123;</span><br><span class="line">  <span class="keyword">if</span> (isWeChatMiniProgram) &#123;</span><br><span class="line">    wx.scanCode();</span><br><span class="line">  &#125; <span class="keyword">else</span> <span class="keyword">if</span> (isMiniApp) &#123;</span><br><span class="line">    my.scan();</span><br><span class="line">  &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>参考文档：</p>
<ul>
<li><a href="https://opendocs.alipay.com/mini/api" target="_blank" rel="noopener">阿里小程序前端 API</a></li>
<li><a href="https://developers.weixin.qq.com/miniprogram/dev/api/" target="_blank" rel="noopener">微信小程序端 API</a></li>
</ul>

    </div>
    
    
    
    
    <div>
      
        <div>
    
        <div style="text-align:center;color: #ccc;font-size:14px;">-------------本文结束<i class="fa fa-paw"></i>感谢您的阅读-------------</div>
    
</div>

      
    </div>
        <div class="reward-container">
  <div>坚持原创技术分享，您的支持将鼓励我继续创作！</div>
  <button onclick="var qr = document.getElementById('qr'); qr.style.display = (qr.style.display === 'none') ? 'block' : 'none';">
    打赏
  </button>
  <div id="qr" style="display: none;">
      
      <div style="display: inline-block;">
        <img src="/images/alipay.png" alt="Li Yudong 支付宝">
        <p>支付宝</p>
      </div>

  </div>
</div>

        

<div>
<ul class="post-copyright">
  <li class="post-copyright-author">
    <strong>本文作者： </strong>Li Yudong
  </li>
  <li class="post-copyright-link">
    <strong>本文链接：</strong>
    <a href="http://example.com/2021/11/24/%E7%9B%92%E9%A9%AC%E6%8A%80%E6%9C%AF%E6%A0%88%E5%88%9D%E5%AD%A6/Rax%E5%B0%8F%E7%A8%8B%E5%BA%8F%E5%BA%94%E7%94%A8/" title="Rax小程序应用">http://example.com/2021/11/24/盒马技术栈初学/Rax小程序应用/</a>
  </li>
  <li class="post-copyright-license">
    <strong>版权声明： </strong>本博客所有文章除特别声明外，均采用 <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/" rel="noopener" target="_blank"><i class="fab fa-fw fa-creative-commons"></i>BY-NC-SA</a> 许可协议。转载请注明出处！
  </li>
</ul>
</div>

    
      <footer class="post-footer">
          <div class="post-tags">
              <a href="/tags/%E5%85%AC%E5%8F%B8%E6%8A%80%E6%9C%AF%E6%A0%88/" rel="tag"># 公司技术栈</a>
          </div>
    
        

    
        
    <div class="post-nav">
      <div class="post-nav-item">
    <a href="/2021/11/22/%E7%9B%92%E9%A9%AC%E6%8A%80%E6%9C%AF%E6%A0%88%E5%88%9D%E5%AD%A6/RaxWEB%E5%BA%94%E7%94%A8/" rel="prev" title="RaxWEB应用">
      <i class="fa fa-chevron-left"></i> RaxWEB应用
    </a></div>
      <div class="post-nav-item">
    <a href="/2021/11/26/%E7%9B%92%E9%A9%AC%E6%8A%80%E6%9C%AF%E6%A0%88%E5%88%9D%E5%AD%A6/Rax%E7%BB%84%E4%BB%B6%E5%BC%80%E5%8F%91/" rel="next" title="Rax组件开发">
      Rax组件开发 <i class="fa fa-chevron-right"></i>
    </a></div>
    </div>
      </footer>
    
  </article>
  
  
  



          </div>
          

<script>
  window.addEventListener('tabs:register', () => {
    let { activeClass } = CONFIG.comments;
    if (CONFIG.comments.storage) {
      activeClass = localStorage.getItem('comments_active') || activeClass;
    }
    if (activeClass) {
      let activeTab = document.querySelector(`a[href="#comment-${activeClass}"]`);
      if (activeTab) {
        activeTab.click();
      }
    }
  });
  if (CONFIG.comments.storage) {
    window.addEventListener('tabs:click', event => {
      if (!event.target.matches('.tabs-comment .tab-content .tab-pane')) return;
      let commentClass = event.target.classList[1];
      localStorage.setItem('comments_active', commentClass);
    });
  }
</script>

        </div>
          
  
  <div class="toggle sidebar-toggle">
    <span class="toggle-line toggle-line-first"></span>
    <span class="toggle-line toggle-line-middle"></span>
    <span class="toggle-line toggle-line-last"></span>
  </div>

  <aside class="sidebar">
    <div class="sidebar-inner">

      <ul class="sidebar-nav motion-element">
        <li class="sidebar-nav-toc">
          文章目录
        </li>
        <li class="sidebar-nav-overview">
          站点概览
        </li>
      </ul>

      <!--noindex-->
      <div class="post-toc-wrap sidebar-panel">
          <div class="post-toc motion-element"><ol class="nav"><li class="nav-item nav-level-1"><a class="nav-link" href="#前言"><span class="nav-number">1.</span> <span class="nav-text">前言</span></a><ol class="nav-child"><li class="nav-item nav-level-2"><a class="nav-link" href="#背景"><span class="nav-number">1.1.</span> <span class="nav-text">背景</span></a></li><li class="nav-item nav-level-2"><a class="nav-link" href="#组件与API"><span class="nav-number">1.2.</span> <span class="nav-text">组件与API</span></a></li></ol></li><li class="nav-item nav-level-1"><a class="nav-link" href="#应用配置"><span class="nav-number">2.</span> <span class="nav-text">应用配置</span></a><ol class="nav-child"><li class="nav-item nav-level-2"><a class="nav-link" href="#项目创建"><span class="nav-number">2.1.</span> <span class="nav-text">项目创建</span></a></li><li class="nav-item nav-level-2"><a class="nav-link" href="#应用入口"><span class="nav-number">2.2.</span> <span class="nav-text">应用入口</span></a></li><li class="nav-item nav-level-2"><a class="nav-link" href="#工程配置"><span class="nav-number">2.3.</span> <span class="nav-text">工程配置</span></a><ol class="nav-child"><li class="nav-item nav-level-4"><a class="nav-link" href="#添加小程序配置"><span class="nav-number">2.3.0.1.</span> <span class="nav-text">添加小程序配置</span></a></li><li class="nav-item nav-level-4"><a class="nav-link" href="#示例配置"><span class="nav-number">2.3.0.2.</span> <span class="nav-text">示例配置</span></a></li></ol></li></ol></li></ol></li><li class="nav-item nav-level-1"><a class="nav-link" href="#应用开发"><span class="nav-number">3.</span> <span class="nav-text">应用开发</span></a><ol class="nav-child"><li class="nav-item nav-level-2"><a class="nav-link" href="#生命周期及事件处理"><span class="nav-number">3.1.</span> <span class="nav-text">生命周期及事件处理</span></a><ol class="nav-child"><li class="nav-item nav-level-3"><a class="nav-link" href="#API"><span class="nav-number">3.1.1.</span> <span class="nav-text">API</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#注意"><span class="nav-number">3.1.2.</span> <span class="nav-text">注意</span></a></li></ol></li><li class="nav-item nav-level-2"><a class="nav-link" href="#组件使用"><span class="nav-number">3.2.</span> <span class="nav-text">组件使用</span></a><ol class="nav-child"><li class="nav-item nav-level-4"><a class="nav-link" href="#自定义组件"><span class="nav-number">3.2.0.1.</span> <span class="nav-text">自定义组件</span></a></li><li class="nav-item nav-level-4"><a class="nav-link" href="#Rax-基础组件"><span class="nav-number">3.2.0.2.</span> <span class="nav-text">Rax 基础组件</span></a></li><li class="nav-item nav-level-4"><a class="nav-link" href="#Fusion-Mobile"><span class="nav-number">3.2.0.3.</span> <span class="nav-text">Fusion Mobile</span></a></li></ol></li></ol></li><li class="nav-item nav-level-2"><a class="nav-link" href="#小程序-API"><span class="nav-number">3.3.</span> <span class="nav-text">小程序 API</span></a><ol class="nav-child"><li class="nav-item nav-level-3"><a class="nav-link" href="#Uni-API"><span class="nav-number">3.3.1.</span> <span class="nav-text">Uni API</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#原生小程序-API"><span class="nav-number">3.3.2.</span> <span class="nav-text">原生小程序 API</span></a></li></ol></li></ol></li></ol></div>
      </div>
      <!--/noindex-->

      <div class="site-overview-wrap sidebar-panel">
        <div class="site-author motion-element" itemprop="author" itemscope itemtype="http://schema.org/Person">
    <img class="site-author-image" itemprop="image" alt="Li Yudong"
      src="/images/author.jpg">
  <p class="site-author-name" itemprop="name">Li Yudong</p>
  <div class="site-description" itemprop="description"></div>
</div>
<div class="site-state-wrap motion-element">
  <nav class="site-state">
      <div class="site-state-item site-state-posts">
          <a href="/archives/">
        
          <span class="site-state-item-count">95</span>
          <span class="site-state-item-name">日志</span>
        </a>
      </div>
      <div class="site-state-item site-state-categories">
            <a href="/categories/">
          
        <span class="site-state-item-count">14</span>
        <span class="site-state-item-name">分类</span></a>
      </div>
      <div class="site-state-item site-state-tags">
            <a href="/tags/">
          
        <span class="site-state-item-count">18</span>
        <span class="site-state-item-name">标签</span></a>
      </div>
  </nav>
</div>
  <div class="links-of-author motion-element">
      <span class="links-of-author-item">
        <a href="https://github.com/tiarmor1" title="GitHub → https:&#x2F;&#x2F;github.com&#x2F;tiarmor1" rel="noopener" target="_blank"><i class="fab fa-github fa-fw"></i>GitHub</a>
      </span>
      <span class="links-of-author-item">
        <a href="mailto:1157019137@qq.com" title="E-Mail → mailto:1157019137@qq.com" rel="noopener" target="_blank"><i class="fa fa-envelope fa-fw"></i>E-Mail</a>
      </span>
  </div>
  <div class="cc-license motion-element" itemprop="license">
    <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/" class="cc-opacity" rel="noopener" target="_blank"><img src="/images/cc-by-nc-sa.svg" alt="Creative Commons"></a>
  </div>



      </div>

    </div>
  </aside>
  <div id="sidebar-dimmer"></div>


      </div>
    </main>

    <footer class="footer">
      <div class="footer-inner">
        

        

<div class="copyright">
  
  &copy; 2020 – 
  <span itemprop="copyrightYear">2022</span>
  <span class="with-love">
    <i class="fa fa-heart"></i>
  </span>
  <span class="author" itemprop="copyrightHolder">Li Yudong</span>
</div>

        








      </div>
    </footer>
  </div>

  
  
  <script color='0,0,0' opacity='0.5' zIndex='-1' count='150' src="/lib1/canvas-nest/canvas-nest.min.js"></script>
  <script src="/lib1/anime.min.js"></script>
  <script src="/lib1/velocity/velocity.min.js"></script>
  <script src="/lib1/velocity/velocity.ui.min.js"></script>

<script src="/js/utils.js"></script>

<script src="/js/motion.js"></script>


<script src="/js/schemes/pisces.js"></script>


<script src="/js/next-boot.js"></script>




  




  
<script src="/js/local-search.js"></script>













  

  

  
   <canvas class="fireworks" style="position: fixed;left: 0;top: 0;z-index: 1; pointer-events: none;" ></canvas> 
   <script type="text/javascript" src="//cdn.bootcss.com/animejs/2.2.0/anime.min.js"></script> 
   <script type="text/javascript" src="/js/fireworks.js"></script>
  
</body>
</html>

